3301583 - SAP SuccessFactors SAML Assertion format demonstration using MS Azure

You wish to learn how to generate a SAML assertion for SAP SuccessFactors SFAPI/ODATA API using Microsoft Active Directory (AD).

"Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental"

IMPORTANT NOTES:

1. This implementation does not belong to SAP and this KBA is merely published for demonstration purposes and developers' know-how only. For help with the implementation, contact Azure support/consultors.
2. Azure AD is one of many IDP products available in the market, in this KBA we are using it merely as an example to illustrate how to use 3rd-party IDP in SuccessFactors OAuth2 flow. SAP does not endorse any specific software for 3rd-party IDP products.
3. Any software coding and/or code snippets are examples. If you use any examples to help generate a SAML Assertion that will be used in a production environment, you are solely responsible for ensuring the security of such a SAML Assertion. SAP does not warrant the correctness and completeness of the example code and such code is delivered “AS-IS”. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct.
4. Please ensure to update the validity date of the SAML Assertion for Production grade scenarios.
5. Software Vendors who want to re-use the sample code in their platform, need to check the code with their security team and legal team (for 3rd party licensing) and then re-use it accordingly.

 

SAP SuccessFactors OData API
SAP SuccessFactors SFAPI

OVERVIEW

1. Use a Chrome browser and make sure you can visit google.com

2. Setup a MS Azure free account
2.1 Visit https://developer.microsoft.com/en-us/microsoft-365/dev-program
2.2 After login, choose the default "instant sandbox" which already includes "Active Directory"
2.3 Now login to your azure portal: https://portal.azure.com/#home

3. Prepare the private/public key
3.1 If using OpenSSL:
3.2 If using the SAP SuccessFactors application "Manage OAuth2 Client Applications":

4. In Azure, create a dummy app that represents your middleware/integration system
4.1 Create the client_id/client_secret
4.2 Create a scope (in this example it is called dummyScope)

5. In Azure, modify one existing user's attribute (for example user.surname which will be used in the subject -> nameid of the SAML assertion)

6. In Azure, install the "SAP SuccessFactors" Enterprise Application, which will generate SAML Assertion
6.1 Modify the identifier or Entity ID (which will be used in the subject -> audience of the SAML assertion)
6.2 Modify the reply url or Assertion Consumer Service URL (which will be used in the subject -> recipient of the SAML assertion)
6.3 Add a Sign on URL (mandatory)
6.4 Add an attribute to represent the api_key (the one you noted in Bizx)
6.5 Create the scope (in this example it is called sapScope) and grant consent to the dummy app to visit the scope and vice-versa

You're done! Let's test



___________________________________________________________________________________

 

 

1. Use a Chrome browser and make sure you can visit google.com

2. Setup a MS Azure free account



2.1 Visit https://developer.microsoft.com/en-us/microsoft-365/dev-program 

(if the login page is stuck at "Send Code", check if your browser can visit google.com because the "Send Code" button needs to visit a js file from Google)

Result:





2.2 After login, choose the default "instant sandbox" which already includes "Active Directory"
It will prompt you to set a password for the Administrator and you will have a sub domain e.g. admin@p8r1.onmicrosoft.com

2.3 Now login to your azure portal: https://portal.azure.com/#home

3. Prepare the private/public key
The key pair will be used by the SuccessFactors' "Manage OAuth2 Client Applications" and the ActiveDirectory SAML SSO App 
You may chose to generate these keys via OpenSSL or the SAP SuccessFactors UI

3.1 If using OpenSSL:

1. Generate 2048-bit RSA private key:
openssl genrsa -out key.pem 2048
2. Generate a Certificate Signing Request:
openssl req -new -sha256 -key key.pem -out csr.csr
3. Generate a self-signed x509 certificate suitable for use on web servers:
openssl req -x509 -sha256 -days 365 -key key.pem -in csr.csr -out certificate.pem




3.2 If using the SAP SuccessFactors application "Manage OAuth2 Client Applications":


NOTES:
Setting up an application in "Manage OAuth2 Client Applications" is a mandatory step, so make sure to store the following safely:
- your API endpoint, in our test case it will be: https://api68sales.successfactors.com
- the generated Public Key file (certificate.pem), and
- the "API Key" which will be used in the ActiveDirectory Enterprise Application (explained in the sections below)

MS AD only recognizes files in the PKCS12 format, so follow these conversion steps in OpenSSL:
- Create an SSL identity file in PKCS12 as mentioned here:
openssl pkcs12 -export -out client-identity.pfx -inkey key.pem -in certificate.pem
- You will be prompted to set a password, set it to "changeit" (or a password of your choice)

4. In Azure, create a dummy app that represents your middleware/integration system

For our test, the application will be called TestLaura

Then go to AD:

Then go to App registrations



4.1 Create the client_id/client_secret

Under "Display name" click on your application (TestLaura in this example):

Go to Certificates & secrets

Create client ID/client secret (note client secret values cannot be viewed, except for immediately after creation. Be sure to save the secret when created before leaving the page)

4.2 Create a scope (in this example it is called dummyScope)

 

5. In Azure, modify one existing user's attribute (for example user.surname which will be used in the subject -> nameid of the SAML assertion)

The purpose of this change is to facilitate your testing:

then:

 

6. In Azure, install the "SAP SuccessFactors" Enterprise Application, which will generate SAML Assertion

6.1 Modify the identifier or Entity ID (which will be used in the subject -> audience of the SAML assertion)

In Azure, install the "SAP SuccessFactors" Enterprise Application, which will generate the SAML Assertion:

Then:

Navigate to SAP SuccessFactors > Set up single sign on > SAML

(In our test, the identifier will be https://api68sales.successfactors.com)
Open Basic SAML Configuration by clicking “Edit” and follow the next steps


6.2 Modify the reply url or Assertion Consumer Service URL (which will be used in the subject -> recipient of the SAML assertion)

In this test, the reply URL will be https://api68sales.successfactors.com/oauth/token 

6.3 Add a Sign on URL (mandatory)


6.4 Add an attribute to represent the api_key (the one you noted in step 3.2)

Open Attributes & Claims by clicking "Edit" > "+ Add new claim"

Double-check the Unique User Identifier:

Result:

6.5 Create the scope (in this example it is called sapScope) and grant consent to the dummy app to visit the scope and vice-versa

Back to App registrations -> SAP SuccessFactors -> Expose an API

+ Add a scope





Scroll down, + Add a client application
(the application ID is the Application (client) ID you set up under App registrations (in this test, it was TestLaura - 3076c2c7*****)







The same goes for the dummy App (assign your dummy app ID to the authorized clients of the SuccessFactors application):

Finally, due to security constraints, it is now required to explicitly assign the user to a SAML-enabled enterprise app. To do so, select your enterprise app for the SuccessFactors system in AAD and click on the “Assign users and groups” tile in the overview (cf. error message https://login.microsoftonline.com/error?code=500133)

From there, select and assign the user(s) or group(s) who need SAML-based access as follows:

 

You're done! Let's test

A) Generate JWT token from azure active directory

-The 17f6864c-***** represents your Azure tenant id

- The scope "api://3076c2c7-******/dummyScope" represents the dummy app's scope (we called it dummyScope above)

- The client_id/client_secret is copied from the dummy app

B) Generate a SAML assertion from MS Azure Active Directory

- The assertion is the response from above jwt token request.

- The client_id/client_secret is the same as the above request.

- The scope is changed to SAP SuccessFactors' scope (we called it sapScope above)

C) Exchange Access token by the SAML assertion in HXM Suite

D) Generate the SAML assertion directly from the SAP SuccessFactors App (no need for the dummy app)

- In this case, we must use the client_id/client_secret from the SAP SuccessFactors App (not the dummy app)

- The scope is also from the SAP SuccessFactors App

- add "requested_token_type" parameter

 
FAQ

 
Q1) Why we need multiple apps to finally generate SAML assertion instead of a single app (just the SAP SuccessFactors app)?
A1) Technically we can just use one app (the SAP SuccessFactors App) to generate SAML assertion. However in case you have multiple clients, it is better to use multiple apps:
In other words, although there should not be an immediate security risk, keeping the app registration for the backend separate from the client app registration(s) helps in scenarios where you may have multiple clients (mobile, web etc.) requiring access to the backend. In this case you’d have different ids and secrets per client app and do not share the same id/secret from the backend app registration across all these client apps. From a security perspective this may be seen as a more secure approach than having only one central pair of client credentials.

Q2) What are common errors encountered during testing?
A2) Please see below for common errors and resolution:

https://login.microsoftonline.com/error?code=50126
Error Code    50126
Message    Error validating credentials due to invalid username or password.
Remediation    The user didn't enter the right credentials.  It's expected to see some number of these errors in your logs due to users making mistakes.
Try resetting the AD password for that user and retry

https://login.microsoftonline.com/error?code=700016
Error Code    700016
Message    Application with identifier '{appIdentifier}' was not found in the directory '{tenantName}'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant.
Remediation    The application named X was not found in the tenant named Y. This can happen if the application with identifier X has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have misconfigured the Identifier value for the application or sent your authentication request to the wrong tenant

https://login.microsoftonline.com/error?code=500011
Error Code    500011
Message    The resource principal named {name} was not found in the tenant named {tenant}. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.
Remediation    Developer error - the app requested access to a resource (application) that isn't installed in your tenant. If you expect the app to be installed, you may need to provide administrator permissions to add it. Check with the developers of the resource and application to understand what the right setup for your tenant is.

https://login.microsoftonline.com/error?code=50105
Error Code    50105
Message    Your administrator has configured the application {appName} ('{appId}') to block users unless they are specifically granted ('assigned') access to the application. The signed in user '{user}' is blocked because they are not a direct member of a group with access, nor had access directly assigned by an administrator. Please contact your administrator to assign access to this application.
Remediation    Assign the user to the app. See https://docs.microsoft.com/azure/active-directory/manage-apps/methods-for-assigning-users-and-groups and https://docs.microsoft.com/azure/active-directory/manage-apps/application-sign-in-problem-federated-sso-gallery#user-not-assigned-a-role

• 3031657 - SAP SuccessFactors SAML Assertion format demonstration using SAP Provided offline tool
• 3146449    OAuth Authentication: Frequently Asked Questions (FAQ)
• If using Postman, see attachments for a Postman script

MS, Microsoft, Azure, Active Directory, SAML Assertion Generation, SAML, assertion, assertion generation , KBA , LOD-SF-INT-ODATA-OAU , ODATA OAUTH Authentication , LOD-SF-INT-ODATA , OData API Framework , LOD-SF-INT-API , API & Adhoc API Framework , LOD-SF-INT-CE , Compound Employee API , How To

SAP SuccessFactors HCM suite all versions